home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / uplevel.n < prev    next >
Encoding:
Text File  |  1994-12-17  |  2.7 KB  |  67 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) uplevel.n 1.2 94/12/17 16:19:11
  9. '\" 
  10. .so man.macros
  11. .HS uplevel tcl
  12. .BS
  13. '\" Note:  do not modify the .SH NAME line immediately below!
  14. .SH NAME
  15. uplevel \- Execute a script in a different stack frame
  16. .SH SYNOPSIS
  17. \fBuplevel \fR?\fIlevel\fR?\fI arg \fR?\fIarg ...\fR?
  18. .BE
  19.  
  20. .SH DESCRIPTION
  21. .PP
  22. All of the \fIarg\fR arguments are concatenated as if they had
  23. been passed to \fBconcat\fR; the result is then evaluated in the
  24. variable context indicated by \fIlevel\fR.  \fBUplevel\fR returns
  25. the result of that evaluation.
  26. .PP
  27. If \fIlevel\fR is an integer then
  28. it gives a distance (up the procedure calling stack) to move before
  29. executing the command.  If \fIlevel\fR consists of \fB#\fR followed by
  30. a number then the number gives an absolute level number.  If \fIlevel\fR
  31. is omitted then it defaults to \fB1\fR.  \fILevel\fR cannot be
  32. defaulted if the first \fIcommand\fR argument starts with a digit or \fB#\fR.
  33. .PP
  34. For example, suppose that procedure \fBa\fR was invoked
  35. from top-level, and that it called \fBb\fR, and that \fBb\fR called \fBc\fR.
  36. Suppose that \fBc\fR invokes the \fBuplevel\fR command.  If \fIlevel\fR
  37. is \fB1\fR or \fB#2\fR  or omitted, then the command will be executed
  38. in the variable context of \fBb\fR.  If \fIlevel\fR is \fB2\fR or \fB#1\fR
  39. then the command will be executed in the variable context of \fBa\fR.
  40. If \fIlevel\fR is \fB3\fR or \fB#0\fR then the command will be executed
  41. at top-level (only global variables will be visible).
  42. .PP
  43. The \fBuplevel\fR command causes the invoking procedure to disappear
  44. from the procedure calling stack while the command is being executed.
  45. In the above example, suppose \fBc\fR invokes the command
  46. .DS
  47. \fBuplevel 1 {set x 43; d}
  48. .DE
  49. where \fBd\fR is another Tcl procedure.  The \fBset\fR command will
  50. modify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute
  51. at level 3, as if called from \fBb\fR.  If it in turn executes
  52. the command
  53. .DS
  54. \fBuplevel {set x 42}
  55. .DE
  56. then the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's
  57. context:  the procedure \fBc\fR does not appear to be on the call stack
  58. when \fBd\fR is executing.  The command ``\fBinfo level\fR'' may
  59. be used to obtain the level of the current procedure.
  60. .PP
  61. \fBUplevel\fR makes it possible to implement new control
  62. constructs as Tcl procedures (for example, \fBuplevel\fR could
  63. be used to implement the \fBwhile\fR construct as a Tcl procedure).
  64.  
  65. .SH KEYWORDS
  66. context, stack frame, variables
  67.